# 编程教程
```{admonition} 本文引用的文件
:class: note
- [docs/docs/zh_CN/index.rst](../../../../products/mpython/index.rst)
- [docs/docs/zh_CN/tutorials/basics/index.rst](../../../../products/mpython/tutorials/basics/index.rst)
- [docs/docs/zh_CN/tutorials/advance/index.rst](../../../../products/mpython/tutorials/advance/index.rst)
- [docs/docs/zh_CN/tutorials/basics/repl.rst](../../../../products/mpython/tutorials/basics/repl.rst)
- [docs/docs/zh_CN/tutorials/basics/oled.rst](../../../../products/mpython/tutorials/basics/oled.rst)
- [docs/docs/zh_CN/tutorials/basics/buttons.rst](../../../../products/mpython/tutorials/basics/buttons.rst)
- [docs/docs/zh_CN/tutorials/basics/accelerometer.rst](../../../../products/mpython/tutorials/basics/accelerometer.rst)
- [docs/docs/zh_CN/tutorials/advance/random.rst](../../../../products/mpython/tutorials/advance/random.rst)
- [docs/docs/zh_CN/tutorials/advance/filesystem.rst](../../../../products/mpython/tutorials/advance/filesystem.rst)
- [docs/docs/zh_CN/tutorials/advance/timer.rst](../../../../products/mpython/tutorials/advance/timer.rst)
- [docs/docs/zh_CN/tutorials/advance/radio.rst](../../../../products/mpython/tutorials/advance/radio.rst)
```
## 产品概述
本教程面向K12创客教育场景，提供从入门到进阶的系统化学习路径，覆盖掌控板全部板载功能。内容以“入门教程（basics）+ 进阶教程（advance）”为主线，结合示例代码与API文档，帮助学习者快速掌握MicroPython在掌控板上的开发方法。项目基于ESP32双核芯片的mPython掌控板，兼容micro:bit部分生态（如music模块），并提供丰富的扩展库与社区资源。
- 目标用户：初学者、教师、创客爱好者
- 核心价值：循序渐进、贴近硬件、可立即验证
- 适用场景：课堂实验、课后练习、项目原型开发
章节来源
- [docs/docs/zh_CN/index.rst:6-30](../../../../products/mpython/index.rst)
## 核心业务流程
本节梳理从“环境搭建—交互调试—外设控制—数据持久化—通信组网”的完整学习链路，对应教程目录与示例工程。
```text
flowchart TD
A["开始：安装驱动与串口终端"] --> B["REPL交互调试
导入 mpython 模块"]
B --> C["基础外设控制
OLED显示/按键/触摸/声音/光线/加速度"]
C --> D["进阶能力
随机数/文件系统/定时器/无线广播"]
D --> E["综合实践
示例工程与经典案例"]
E --> F["拓展方向
网络/IoT/蓝牙/传感器扩展"]
```
章节来源
- [docs/docs/zh_CN/tutorials/basics/index.rst:4-19](../../../../products/mpython/tutorials/basics/index.rst)
- [docs/docs/zh_CN/tutorials/advance/index.rst:4-15](../../../../products/mpython/tutorials/advance/index.rst)
## 功能模块清单
以下按“入门→进阶”顺序列出各模块职责、用户价值与验收要点，便于对照学习与自测。
- REPL（交互式调试）
- 职责：通过串口终端进行即时代码执行与调试
- 用户价值：降低试错成本，快速验证想法
- 验收要点：能连接串口、进入>>>提示符、执行print与简单表达式、使用Tab补全与粘贴模式
- 参考：[docs/docs/zh_CN/tutorials/basics/repl.rst:9-147](../../../../products/mpython/tutorials/basics/repl.rst)
- OLED显示
- 职责：文本、图形、图片绘制与刷新
- 用户价值：直观反馈程序状态与结果
- 验收要点：DispChar显示中文、fill/pixel/hline/vline/rect等绘图、bitmap显示图片、show刷新
- 参考：[docs/docs/zh_CN/tutorials/basics/oled.rst:12-136](../../../../products/mpython/tutorials/basics/oled.rst), [docs/docs/zh_CN/tutorials/basics/oled.rst:139-235](../../../../products/mpython/tutorials/basics/oled.rst)
- 按键与中断
- 职责：读取A/B按键电平与事件；配置中断回调
- 用户价值：实现人机交互与低功耗响应
- 验收要点：value()判断按下/松开；irq()下降沿触发回调；回调函数含参数
- 参考：[docs/docs/zh_CN/tutorials/basics/buttons.rst:15-58](../../../../products/mpython/tutorials/basics/buttons.rst)
- 加速度计
- 职责：读取三轴加速度并计算角度/倾斜
- 用户价值：感知姿态变化，用于水平仪、摇一摇等
- 验收要点：get_x/y/z获取mg值；映射numberMap到屏幕坐标；反余弦计算倾角
- 参考：[docs/docs/zh_CN/tutorials/basics/accelerometer.rst:16-145](../../../../products/mpython/tutorials/basics/accelerometer.rst)
- 随机数
- 职责：生成随机整数、浮点数与选择元素
- 用户价值：游戏逻辑、动画效果、测试数据
- 验收要点：randint/randrange/random/uniform；seed可重现序列
- 参考：[docs/docs/zh_CN/tutorials/advance/random.rst:1-103](../../../../products/mpython/tutorials/advance/random.rst)
- 文件系统
- 职责：读写文件、列举/删除文件、boot.py/main.py启动流程
- 用户价值：持久化配置、素材存储、模块化组织
- 验收要点：open with上下文管理；write/read；os.listdir/remove；main.py自动运行
- 参考：[docs/docs/zh_CN/tutorials/advance/filesystem.rst:28-178](../../../../products/mpython/tutorials/advance/filesystem.rst)
- 定时器
- 职责：周期性或单次触发回调
- 用户价值：定时任务、节拍控制、异步事件
- 验收要点：Timer.init(period, mode, callback)；value()读计数；注意UI刷新延时
- 参考：[docs/docs/zh_CN/tutorials/advance/timer.rst:14-45](../../../../products/mpython/tutorials/advance/timer.rst)
- 无线广播（radio）
- 职责：2.4G短距无线收发，多设备组网
- 用户价值：对讲机、电报机、分布式传感
- 验收要点：on()/config(channel)/send()/receive()；可选返回MAC地址
- 参考：[docs/docs/zh_CN/tutorials/advance/radio.rst:14-57](../../../../products/mpython/tutorials/advance/radio.rst)
章节来源
- [docs/docs/zh_CN/tutorials/basics/index.rst:4-19](../../../../products/mpython/tutorials/basics/index.rst)
- [docs/docs/zh_CN/tutorials/advance/index.rst:4-15](../../../../products/mpython/tutorials/advance/index.rst)
## 数据与状态
- 输入数据流
- 传感器：加速度计三轴值（mg）、按键电平（0/1）、触摸阈值原始值
- 外部通信：radio接收字符串或字节，可选附带MAC
- 文件：读取文本/二进制数据（如图片帧）
- 内部状态
- 显示缓冲：FrameBuffer/OLED缓冲区，需show刷新
- 定时器：周期计数与回调队列
- 随机种子：seed决定伪随机序列
- 输出数据流
- 显示：字符、图形、图片帧
- 音频/灯光：音乐播放、RGB指示
- 通信：radio发送消息
- 数据所有权边界
- 板载模块（mpython.*）负责硬件抽象与状态封装
- 应用层（用户脚本）负责业务逻辑与数据编排
- 文件系统仅作为持久化载体，不持有运行时状态
```text
graph LR
S["传感器/IO"] --> M["mpython 模块"]
M --> D["显示缓冲/定时器/随机状态"]
D --> O["OLED/音乐/RGB"]
M --> N["radio 收发"]
M --> FS["文件系统(持久化)"]
```
## 关键约束与边界
- 平台与环境
- 串口波特率115200；Windows需安装cp2104驱动
- MicroPython为精简版，文件系统为平面结构（无多级目录）
- 硬件限制
- 特定引脚不可用作通用IO（如P4/P10分别用于光线/声音传感器）
- 显示刷新需调用show()；UI刷新可能引入延时影响定时精度
- 通信与网络
- radio为同频短距通信，需设置相同channel；receive(True)可获取MAC
- 网络相关能力在进阶与扩展中涉及（本仓库示例涵盖网络类示例）
- 性能与功耗
- 频繁刷新显示与I/O会占用CPU与电量，建议批量更新与休眠策略
- 定时器回调应避免耗时操作，必要时拆分任务
章节来源
- [docs/docs/zh_CN/tutorials/basics/repl.rst:9-147](../../../../products/mpython/tutorials/basics/repl.rst)
- [docs/docs/zh_CN/tutorials/advance/filesystem.rst:21-25](../../../../products/mpython/tutorials/advance/filesystem.rst)
- [docs/docs/zh_CN/tutorials/advance/timer.rst:39-45](../../../../products/mpython/tutorials/advance/timer.rst)
- [docs/docs/zh_CN/tutorials/advance/radio.rst:29-32](../../../../products/mpython/tutorials/advance/radio.rst)